home *** CD-ROM | disk | FTP | other *** search
/ Deutsche Edition 1 / Deutsche Edition 1.iso / amok / 051-060 / amok51 / amok-poster next >
Text File  |  1993-11-04  |  8KB  |  159 lines
  1. ======================================================================
  2.            AMOK - AMIGA Modula & Oberon Klub  Stuttgart
  3.  
  4.      "AMOK-Poster": Norm bzw. Standardform für AMOK-Beiträge
  5.           Tips und Anhaltspunkte für Veröffentlichungen
  6. ======================================================================
  7.  
  8. Einleitung
  9.  
  10. Wir -AMOK- sind gerne bereit, auch anderen Modula-2- bzw. Oberon-
  11. Programmierern mit den AMOK-Disks einen Weg zur Veröffentlichung
  12. Ihrer Programme zu bieten. Ziel unserer PD-Reihe ist es schließlich,
  13. für eine möglichst weite Verbreitung von Modula & Oberon zu sorgen.
  14. Da sich diese Programmiersprachen optimal zum Austausch von Programm-
  15. Modulen eignen, kann jeder Programmierer hierzu beitragen. Je größer
  16. die Modulbibliothek ist, auf die ein Programmierer zurückgreifen kann,
  17. desto weniger muß er sich mit zeitraubenden Alltagsproblemen herum-
  18. schlagen und sozusagen "das Rad zweimal erfinden".
  19. Falls Sie also Module geschrieben haben, von denen Sie denken, daß auch
  20. andere sie gebrauchen können, schicken Sie sie an AMOK. Wenn irgend
  21. möglich werden wir den Beitrag in unsere AMOK-Reihe aufnehmen. Wir
  22. stellen zwar keine Ansprüche an die Genialität der Programme, damit
  23. Ihr Beitrag eine Chance hat, veröffentlicht zu werden, sollten Sie aber
  24. die unten aufgeführten Punkte beachten. Damit gewährleistet ist, daß
  25. Ihre PD-Software auch wirklich brauchbar ist.
  26.  
  27.  
  28. 1) Kriterien
  29.  
  30. Wie schon erwähnt stellen wir keine Anforderungen an das, was ein Programm
  31. besonderes kann. Das was es kann, soll es aber sinnvoll und korrekt aus-
  32. führen. Ein simples aber nützliches Modul hat, auch wenn es noch so banal
  33. ist, höhere Chancen, veröffentlicht zu werden, als ein Riesenprojekt, das an
  34. sich genial ist, aber ständig guru-meditiert.
  35.  
  36.  
  37. 2) AMOK Anforderungen
  38.  
  39. Die Folgenden Punkte sind verbindlich und von jedem AMOK-Beitrag einzuhalten:
  40.  
  41. * Zu jedem Modul(-packet) gehört eine Dokumentation. Ohne Dokumentation
  42.   sind die Module für andere unbrauchbar. Es gibt auf den AMOK-Disketten
  43.   folgende Formen der Dokumentation:
  44.     - Dokumentation im Klartext in einer extra Datei mit der Endung ".dok"
  45.       (für deutsche Dokumentation) oder ".doc" (für die englische)
  46.     - stichwortartige Kurzbeschreibung der Prozeduren im Definitionsmodul
  47.       Diese Form der Dokumentation ist auf AMOK# >= 25 bei "HeaderInfo"
  48.       genauer beschrieben.
  49.   Die Dokumentation sollte mindestens diese Informationen beinhalten:
  50.     - Bedeutung und Auswirkung der Prozedurparameter
  51.     - Funktion und Verwendungszweck der Prozeduren
  52.     - Bedeutung der Rückgabewerte der Prozeduren
  53.     - Wichtige Hinweise über exportierte Variablen, Konstanten und Typen
  54.     - Hinweise auf mögliche Fehler (soweit bekannt)
  55.     - Angaben über eventuelle Einschränkungen oder Warnungen
  56.   Wenn möglich sollte die Dokumentation nur aus reinem ASCII-Code und
  57.   nur mit den ANSI Steuersequenzen geschrieben werden.
  58.   (MuchMore- und copy-to-prt:-verträglich)
  59.  
  60. * Der Source-Code sollte den Modulen immer beigefügt werden. Schließlich
  61.   sollen andere Programmierer aus Ihrem Programm etwas lernen können.
  62.   Außerdem ist es somit möglich, eventuelle Fehler zu verbessern oder
  63.   das Programm an eigene Bedürfnisse anzupassen. Als Ausnahmen sind
  64.   folgende zulässig:
  65.     - das Programm ist wirklich ausgesprochen genial und gehört eigentlich
  66.       patentiert (es muß natürlich absolut fehlerfrei sein)
  67.     - die Module sind Teile eines von Ihnen kommerziell vertriebenen
  68.       Programms, und Sie wollen nicht, daß jemand Einblick erhält
  69.     - Ihr Programmierstil ist so schlecht und Ihre Methoden so haar-
  70.       sträubend, daß Sie den Source-Code niemandem zumuten wollen
  71.       (In diesem Fall sollten Sie sich allerdings Überlegen, ob Sie nicht
  72.       lieber C oder Assembler programmieren wollen)
  73.  
  74. * Definitions und Implementationsmodul sollten unseren Modulkopf (siehe
  75.   "HeaderInfo") beinhalten. Dieser ist zur leichteren Verwaltung der
  76.   inzwischen mehrere Megabyte umfassenden AMOK-Softwarebibliothek notwendig.
  77.   Bitte erfindet keine eigenen ShortCuts! Diese sind den Klubmitgliedern
  78.   vorenthalten! Haltet Euch an unsere Formatvorgaben in "HeaderInfo".
  79.  
  80. * Alle Dateien und Unterdirectories sollen Icons haben, so daß Sie von der
  81.   Workbench aus zugänglich sind. Das Default-Tool von Textdateien (Source
  82.   und Dokumentation) muß auf ":c/MuchMore" eingestellt sein.
  83.  
  84.  
  85. 3) AMOK Vereinbarungen
  86.  
  87. Es wird gebeten, auch auf folgendes zu achten:
  88.  
  89. * Sollten zum Compilieren eines Moduls noch andere nicht standardmäßige
  90.   Module benötigt werden, sollten diese mitgeliefert werden. Dabei ist
  91.   darauf zu achten, daß die sym-Schlüssel stimmen, d.h. alles mit der
  92.   selben Version der Definitionsmodule compiliert wurde. Existieren von
  93.   imortierten Modulen mehrere Versionen, dann ist anzugeben, welche
  94.   benötigt wird. (Vermerk :Imports.)
  95.  
  96. * Im Source-Code und in der Dokumentation sollte man wenn möglich die
  97.   Zeilenlänge auf 70 bis 75 Zeichen begrenzen. MuchMore und M2Emacs
  98.   akzeptieren zwar 80 Zeichen, viele möchten jedoch sicherlich die
  99.   Texte ausdrucken, und da ist ein Rand ganz nützlich.
  100.  
  101. * Prozedur-, Variablen-, Konstanten- und Typenbezeichner sollten
  102.   vorzugsweise englisch sein, ebenso die Kurzbeschreibung der Prozeduren
  103.   im Definitionsmodul (siehe AMOK#7, ProgInfo/StandardIDs).
  104.   Wenigstens sollte man Englisch und Deutsch nicht mischen.
  105.   Deutsche Dokumentation sollte nicht fehlen, englische ist freiwillig.
  106.  
  107. * Kleine Demoprogramme dienen der leichteren Verständnis und dem besseren
  108.   Einarbeiten in die Funktionen eines Moduls. Oft sind Testmodule oder
  109.   sonstige Beispielanwendungen als Nebenprodukte eigener Programme
  110.   sowieso vorhanden.
  111.  
  112. * Seien Sie fair gegenüber anderen Programmierern. Public Domain heißt
  113.   noch lange nicht "Software-Freiwild". Wenn Sie Programmteile von
  114.   anderen übernehmen, erwähnen Sie den Autor bitte im Modulkopf oder in
  115.   Kommentarzeilen. Für eine kommerzielle Nutzung brauchen Sie die
  116.   Schriftliche Erlaubnis des jewiligen Autors. Denken Sie bitte auch
  117.   an eventuelle Shareware-Gebühren.
  118.  
  119.  
  120. 4) Zum Thema korrekte Programme
  121.  
  122. Die folgenden Anweisungen gelten nicht speziell für AMOK-Disketten
  123. sondern sollten von allen Programmierern beachtet werden. Wenn diese
  124. Punkte für Sie noch nicht selbstverständlich sind, empfehlen wir Ihnen
  125. DRINGENDST Ihre Programme in Zukunft dementsprechend auszulegen.
  126.  
  127. * Alle Programme sollten auf korrektem Weg verlassen werden können, das
  128.   heißt, ohne neu starten zu müssen, und so, daß uneingeschränkt weiter-
  129.   gearbeitet werden kann. Außerdem sollen Sie alle Betriebsmittel und
  130.   Resourcen an das System zurückgeben (Speicher deallozieren, Fenster,
  131.   Screens und Files schließen).
  132.  
  133. * Programme sollten sich nicht so verhalten, als wären Sie die einzigen
  134.   im System, sondern auf das Multitasking und seine Restriktionen
  135.   Rücksicht nehmen (z.B. gegenseitiger Ausschluß beim Zugriff auf System-
  136.   strukturen).
  137.  
  138. * Programme sollen sich gegenüber dem Benutzer logisch und bei Fehlein-
  139.   gaben robust verhalten.
  140.  
  141. * Man sollte nie davon ausgehen, immer alle Betriebsmittel zu bekommen,
  142.   die man anfordert. Programme sollen sich definiert verhalten, wenn z.B.
  143.   Files nicht geöffnet werden können, oder nicht mehr genügend Speicher
  144.   vorhanden ist.
  145.  
  146. * Die Benutzerschnittstelle soll den beim AMIGA allgemein üblichen Richt-
  147.   linien entsprechen (siehe Intuition Reference Manual Chapter 12: Style).
  148.  
  149. * Programme sollten wenn möglich keine spezielle Gerätekonfiguration
  150.   vorraussetzen.
  151.  
  152. * Besonders für die Entwicklung zukünftiger Bibliotheksmodule ist wichtig,
  153.   daß die Prozeduren reentrant sind, falls es sinnvoll ist, sie von
  154.   mehreren Tasks aus gleichzeitig zu benutzen (es ist in Modula ja nicht
  155.   möglich, Module zweimal zu importieren).
  156.  
  157. --- Viel Spaß
  158.  
  159.